home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / mimelib / msgcmp.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-14  |  12.5 KB  |  312 lines
  1. //=============================================================================
  2. // File:       msgcmp.h
  3. // Contents:   Declarations for DwMessageComponent
  4. // Maintainer: Doug Sauder <dwsauder@fwb.gulf.net>
  5. // WWW:        http://www.fwb.gulf.net/~dwsauder/mimepp.html
  6. //
  7. // Copyright (c) 1996, 1997 Douglas W. Sauder
  8. // All rights reserved.
  9. //
  10. // IN NO EVENT SHALL DOUGLAS W. SAUDER BE LIABLE TO ANY PARTY FOR DIRECT,
  11. // INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
  12. // THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF DOUGLAS W. SAUDER
  13. // HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. //
  15. // DOUGLAS W. SAUDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT
  16. // NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  17. // PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS"
  18. // BASIS, AND DOUGLAS W. SAUDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
  19. // SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. //
  21. //=============================================================================
  22.  
  23. #ifndef DW_MSGCMP_H
  24. #define DW_MSGCMP_H
  25.  
  26. #ifndef DW_CONFIG_H
  27. #include <mimelib/config.h>
  28. #endif
  29.  
  30. #ifndef DW_STRING_H
  31. #include <mimelib/string.h>
  32. #endif
  33.  
  34. #if !(defined(__DECCXX) && defined(__linux__))
  35. #include <iosfwd>
  36. #endif
  37.  
  38.  
  39. //=============================================================================
  40. //+ Name DwMessageComponent -- Abstract base class for all message components
  41. //+ Description
  42. //. {\tt DwMessageComponent} is the root of an inheritance hierarchy from
  43. //. which all MIME message components are derived.  Thus,
  44. //. {\tt DwMessageComponent} defines important features that are inherited by
  45. //. nearly all other classes that represent components of a MIME message.
  46. //. These features are the following:
  47. //.
  48. //. \begin{enumerate}
  49. //. \item
  50. //.    A string representation.  The {\tt DwMessageComponent} class provides
  51. //.    a member function {\tt FromString(const DwString&)} to set the string
  52. //.    representation and a member function {\tt AsString()} to get the
  53. //.    string representation.
  54. //.
  55. //. \item
  56. //.    A broken-down, or parsed, representation.  An RFC-822 date-time,
  57. //.    for example, has a year, month, day, hour, minute, second, and
  58. //.    time zone as elements of its broken-down representation.
  59. //.    {\tt DwMessageComponent} does not deal directly with the
  60. //.    broken-down representation, since it is component-specific.
  61. //.    Derived classes bear all the responsibility for their broken-down
  62. //.    representations.
  63. //.
  64. //. \item
  65. //.    A parse method to extract the broken-down representation from
  66. //.    the string representation.  In the {\tt DwDateTime} class, for
  67. //.    example, the parse method extracts the year, month, day, hour,
  68. //.    minute, second, and time zone from the RFC-822 {\it date-time}
  69. //.    contained in the string representation.  {\tt DwMessageComponent}
  70. //.    provides a pure virtual function {\tt Parse()}, which executes
  71. //.    the parse method for a derived class.
  72. //.
  73. //. \item
  74. //.    An assemble method to convert the broken-down representation to
  75. //.    a string representation.  This is the opposite of the parse method.
  76. //.    In the {\tt DwDateTime} class, for example, the assemble method
  77. //.    creates an RFC-822 {\it date-time} string from values of the
  78. //.    year, month, day, hour, minute, second, and time zone.
  79. //.    {\tt DwMessageComponent} provides a pure virtual function
  80. //.    {\tt Assemble()}, which executes the assemble method for
  81. //.    a derived class.
  82. //.
  83. //. \item
  84. //.    An is-modified flag.  When the string representation and the
  85. //.    broken-down representation are consistent, the assemble
  86. //.    method does not need to be executed.  The is-modified flag is
  87. //.    cleared when the two representations are consistent, and is set
  88. //.    when they are inconsistent.  The flag is set automatically
  89. //.    whenever a {\tt DwMessageComponent} object's broken-down
  90. //.    representation is changed by calling one of the object's member
  91. //.    functions, and it is cleared when the assemble or parse method
  92. //.    is executed.  {\tt DwMessageComponent} also provides a member
  93. //.    function {\tt SetModified()} which forces the is-modified flag
  94. //.    to be set.
  95. //.
  96. //. \item
  97. //.    A parent.  Most message components are part of another component.
  98. //.    A collection of headers is part of a message or body part, a header
  99. //.    field is part of a collection of headers, a field-body is part
  100. //.    of a header field, and so on.  The parent of
  101. //.    a component is the component that contains it.  This tree structure
  102. //.    is important, since a component's parent must be parsed before the
  103. //.    component can be.  Also, a component's string representation must
  104. //.    be assembled before its parent's.  To maintain consistency in the
  105. //.    tree, whenever a component's is-modified flag is set,
  106. //.    the component notifies its parent to also set its is-modified flag.
  107. //.    In this way, an is-modified flag set anywhere in the tree always
  108. //.    propagates up to the root component.
  109. //.
  110. //. \item
  111. //.    Children.  The preceding discussion about a component's parent is
  112. //.    relevant to an understanding of a component's children.  A component's
  113. //.    parse method calls the parse methods of its children
  114. //.    after it has executed its own parse method (and, in some cases, created
  115. //.    all of its children).
  116. //.    Also, a component typically calls the assemble method of its
  117. //.    children before it executes its own.  A component's child may request
  118. //.    that the component set its is-modified flag.
  119. //.    {\tt DwMessageComponent} does not deal directly with children.
  120. //.    Derived classes bear all the responsibility for handling their
  121. //.    children.
  122. //. \end{enumerate}
  123. //=============================================================================
  124. //+ Noentry ~DwMessageComponent _PrintDebugInfo mString mIsModified mParent
  125. //+ Noentry mClassId mClassName
  126.  
  127. class DW_EXPORT DwMessageComponent {
  128.  
  129. private:
  130.  
  131.     DwUint32 mMagicNumber;
  132.  
  133. public:
  134.  
  135.     enum componentType {
  136.         kCidError=-1,
  137.         kCidUnknown=0,
  138.         kCidAddress,
  139.         kCidAddressList,
  140.         kCidBody,
  141.         kCidBodyPart,
  142.         kCidDispositionType,
  143.         kCidMechanism,
  144.         kCidMediaType,
  145.         kCidParameter,
  146.         kCidDateTime,
  147.         kCidEntity,
  148.         kCidField,
  149.         kCidFieldBody,
  150.         kCidGroup,
  151.         kCidHeaders,
  152.         kCidMailbox,
  153.         kCidMailboxList,
  154.         kCidMessage,
  155.         kCidMessageComponent,
  156.         kCidMsgId,
  157.         kCidText
  158.     };
  159.     //. Class identifier enumeration
  160.  
  161.     DwMessageComponent();
  162.     DwMessageComponent(const DwMessageComponent& aCmp);
  163.     DwMessageComponent(const DwString& aStr, DwMessageComponent* aParent=0);
  164.     //. The first constructor is the default constructor, which sets the
  165.     //. {\tt DwMessageComponent} object's string representation to the
  166.     //. empty string and sets its parent to NULL.
  167.     //.
  168.     //. The second constructor is the copy constructor, which performs
  169.     //. a deep copy of {\tt aCmp}.  The parent of the new
  170.     //. {\tt DwMessageComponent} object is set to NULL.
  171.     //.
  172.     //. The third constructor copies {\tt aStr} to the new
  173.     //. {\tt DwMessageComponent} object's string representation and sets
  174.     //. {\tt aParent} as its parent.  In typical cases, the virtual
  175.     //. member function {\tt Parse()} should be called immediately after
  176.     //. this constructor to parse the new {\tt DwMessageComponent} object
  177.     //. and all of its children into their broken-down representations.
  178.  
  179.     virtual ~DwMessageComponent();
  180.  
  181.     const DwMessageComponent& operator = (const DwMessageComponent& aCmp);
  182.     //. This is the assignment operator, which performs a deep copy of
  183.     //. {\tt aCmp}.
  184.  
  185.     virtual void Parse() = 0;
  186.     //. A pure virtual function which provides an interface to the parse
  187.     //. method.  The parse method, implemented in derived classes, is
  188.     //. responsible for extracting the broken-down representation from
  189.     //. the string representation.  In some derived classes, such as
  190.     //. {\tt DwHeaders}, the parse method is also responsible for creating the
  191.     //. children of the object.  (In the case of {\tt DwHeaders}, the children
  192.     //. created are the {\tt DwField} objects that represent the {\it field}s
  193.     //. contained in the {\it headers}.)  The {\tt Parse()} function always
  194.     //. calls the {\tt Parse()} function of all of its children.
  195.  
  196.     virtual void Assemble() = 0;
  197.     //. A pure virtual function which provides an interface to the
  198.     //. assemble method.  The assemble method, implemented in derived
  199.     //. classes, is responsible for creating the string representation
  200.     //. from the broken-down representation.  In other words, the
  201.     //. assemble method is the opposite of the parse method.  Before
  202.     //. assembling its string representation, the assemble method calls
  203.     //. the assemble method of each of its children.  In this way, the
  204.     //. entire tree structure that represents a message may be traversed.
  205.     //. If the is-modifed flag for a {\tt DwMessageComponent} is cleared,
  206.     //. the {\tt Assemble()} function will return immediately without
  207.     //. calling the {\tt Assemble()} function of any of its children.
  208.  
  209.     virtual DwMessageComponent* Clone() const = 0;
  210.     //. Creates a new {\tt DwMessageComponent} on the free store that is of
  211.     //. the same type as, and has the same value as, this object.  The
  212.     //. basic idea is that of a ``virtual copy constructor.''
  213.  
  214.     void FromString(const DwString& aStr);
  215.     void FromString(const char* aCstr);
  216.     //. Sets the object's string representation.  {\tt aCstr} must be
  217.     //. NUL-terminated. This member function does not invoke the parse
  218.     //. method.  Typically, the virtual member function {\tt Parse()}
  219.     //. should be called immediately after this member function to parse
  220.     //. the {\tt DwMessageComponent} object and all of its children into
  221.     //. their broken-down representations.  See also
  222.     //. {\tt DwMessageComponent::Parse()}
  223.  
  224.     const DwString& AsString();
  225.     //. Returns the {\tt DwMessageComponent} object's string representation.
  226.     //. The assemble method is not called automatically.  Typically, the
  227.     //. {\tt Assemble()} member function should be called immediately before
  228.     //. this member function to insure that the broken-down representation
  229.     //. and the string representation are consistent.  See also
  230.     //. {\tt DwMessageComponent::Assemble()}.
  231.  
  232.     DwMessageComponent* Parent();
  233.     //. Returns the {\tt DwMessageComponent} object that is the parent
  234.     //. of this object.
  235.  
  236.     void SetParent(DwMessageComponent* aParent);
  237.     //. Sets {\tt aParent} as the {\tt DwMessageComponent} object's parent.
  238.  
  239.     DwBool IsModified() const;
  240.     //. Returns 1 if the is-modified flag is set for this
  241.     //. {\tt DwMessageComponent} object.
  242.  
  243.     void SetModified();
  244.     //. Sets the is-modified (dirty) flag for this {\tt DwMessageComponent}
  245.     //. object and notifies the object's parent to also set its is-modified
  246.     //. flag.
  247.  
  248.     int ClassId() const;
  249.     //. Returns an integer id for the object's class.
  250.  
  251.     const char* ClassName() const;
  252.     //. Returns the name of the class as a NUL-terminated
  253.     //. char string.
  254.  
  255.     int ObjectId() const;
  256.     //. Returns a object id that is unique among all DwMessageComponent
  257.     //. objects.
  258.  
  259.     const char* partId() const { return mId.c_str(); };
  260.     void SetPartId( DwString id ) { mId = id; };
  261.     // set or get a unique string for that part
  262.  
  263. protected:
  264.  
  265.     DwString mString;
  266.     // String representation
  267.  
  268.     DwBool mIsModified;
  269.     // Is-modified flag
  270.  
  271.     DwMessageComponent* mParent;
  272.     // Component that contains this component
  273.  
  274.     componentType mClassId;
  275.     // Class identifier for runtime type identification
  276.  
  277.     const char* mClassName;
  278.     // Class name for runtime type identification
  279.  
  280.     DwString mId;
  281.     // unique indentifier
  282.  
  283. private:
  284.  
  285.     static const char* const sClassName;
  286.  
  287. public:
  288.  
  289.     virtual void PrintDebugInfo(std::ostream& aStrm, int aDepth=0) const;
  290.     //. This virtual function
  291.     //. prints debugging information about this object to {\tt aStrm}.
  292.     //. It will also call {\tt PrintDebugInfo()} for any of its child
  293.     //. components down to a level of {\tt aDepth}.
  294.     //.
  295.     //. This member function is available only in the debug version of
  296.     //. the library.
  297.  
  298.     virtual void CheckInvariants() const;
  299.     //. Aborts if one of the invariants of the object fails.  Use this
  300.     //. member function to track down bugs.
  301.     //.
  302.     //. This member function is available only in the debug version of
  303.     //. the library.
  304.  
  305. protected:
  306.  
  307.     void _PrintDebugInfo(std::ostream& aStrm) const;
  308.  
  309. };
  310.  
  311. #endif
  312.